home *** CD-ROM | disk | FTP | other *** search
/ Dr. Windows 3 / dr win3.zip / dr win3 / VISUALBA / DATEMA.ZIP / DATECALC.TXT < prev    next >
Text File  |  1993-03-24  |  13KB  |  339 lines
  1.             DATEMATH
  2.         Working Days Calculator
  3.             (c) 1993
  4.  
  5.  
  6.  
  7.  
  8.  
  9.         Table of Contents
  10.  
  11.     1. Introduction (What Is DATEMATH ?)
  12.  
  13.     2. A Simple Tutorial
  14.  
  15.     3. The Calendar Text File
  16.  
  17.     4. Compiling the Calendar File
  18.  
  19.     5. DATEMATH's Library Functions
  20.  
  21.     6. Oddities of Calendar Math
  22.  
  23.     7. Coming Soon From Expertec
  24.  
  25.     8. Registration & Legal Info
  26.  
  27.  
  28.  
  29.  
  30.  
  31. 1. Introduction (What Is DATEMATH ?)
  32. -----------------------------------------------------------------------
  33.  
  34. DATEMATH is a dynamic link library that allows developers to give their
  35. applications the ability to real date math. While most programming 
  36. languages give you some minimal capabilities for date manipulation, 
  37. DATEMATH will allow you to add accuracy to your programs. 
  38. For instance, most language products could tell you that there is 59 days 
  39. between Jan 1, 1993 and Mar 1, 1993. But while DATEMATH can tell you that, 
  40. it can also tell you that there is 39 work days between those dates. 
  41. ( If company allows more holidays, the number of work days 
  42. could be even less ). 
  43.  
  44. There are three basic elements to DATEMATH. They are:
  45.     A. The DATEMATH DLL
  46.     B. The Calandar Text File
  47.     C. The Calendar Binary File 
  48.  
  49. A. The DATEMATH DLL handles the three eccential date functions consisting
  50. of DCalDIF ( a function that returns  the difference in working days
  51. between two dates), DCalADD (a function that allows you to add x number
  52. of work days to a start date and returns the finish date), and
  53. DCalSUB ( a function that allows you to subtract x number of work days
  54. from a finish date and returns the start date). DATEMATH also includes
  55. functions for loading and unloading various user calendars. Registered
  56. users of DATEMATH will also be given access to additional functions in
  57. DATEMATH as well as a Calendar Maintanence program.
  58.  
  59. B. The Calendar Text File is a simple ASCII file that contains a listing
  60. of the two basic rest types, namely Rest Days and Holidays. An example
  61. of a Rest Day is SUNDAY. Rest Days refer to Days of the Week. An example
  62. of a Holiday is 12/25/93. Holidays refer to a specific date in time. More
  63. on the calendar text files later.
  64.  
  65. C. The Calendar Binary File is produced when the program CalMaint.EXE
  66. compiles the calendar text file. The DATEMATH DLL reads the calendar
  67. binary file when the LoadCalendar Function is called. The program
  68. CalMaint.EXE is a windows based program that is not included with
  69. the demo version of DATEMATH. However when you register DATEMATH you
  70. will recieve a copy of the CalMaint program at no additional cost. 
  71. More on this later. 
  72.  
  73.  
  74. 2. A Simple Tutorial
  75. ---------------------------------------------------------------------
  76.  
  77. When you start the program the cursor will blinking in a text box labeled
  78. start date. Type 1/1/93 and hit the {TAB} key. In the next box type
  79. 2/1/93 and hit the {TAB} key. Next Click the Difference button and
  80. note the answer in the Results box. Next try selecting different calendars
  81. from the Calendar Group box. As you select different calendars the results
  82. boxes will clear. Click again on the Difference and note the new results.
  83. Its that simple. 
  84.  
  85.  
  86. 3. The Calendar Text File
  87. ---------------------------------------------------------------------
  88.  
  89. The Calendar Text is a simple text file that allows the developer to
  90. define up to eight seperate work calendars. The Calendar text holds
  91. calendar names and their respective rest and holiday information. 
  92. There is three types of data that can be in a calendar text file. They
  93. are Rest Lines, Holiday Lines and Comment Lines. 
  94.  
  95. Rest Lines and Holiday Lines are made up of two parts. The first part
  96. is the calendar name and the second part is the day value.
  97.  
  98. Here are some examples of Rest Lines:
  99.                 FiveDay Saturday
  100.                 FiveDay Sunday
  101. In the above example we have created a calendar called FiveDay and
  102. specified Saturday and Sunday as rest days. Please note the calendar
  103. name 'FiveDay'. One of the only rules we have when your using DATEMATH
  104. is that calendar names cannot exceed 8 characters and the first character
  105. must be a letter.
  106.  
  107. Here are some examples of Holiday Lines:
  108.                 FiveDay    18-Jan-93
  109.                 FiveDay 15-Feb-93
  110. In this example we have specified 18-Jan-93 ( Dr. Martin Luther Kings
  111. Birthday ) and 15-Feb-93 ( Presidents Day ) as non-work days. Each
  112. calendar can have up to 200 holidays.
  113.  
  114. Here are some example of Comment lines
  115.             // Anything That Doesn't Look
  116.             */ Like a Rest or Holiday
  117.             ; line gets interpeted as a Comment.
  118.  
  119. Below is the Calendar Text File Used in the Sample application.
  120.  
  121. //This is the Calendar Text File (CALDATA.TXT).
  122. // Note that the file can contain blank lines for clarity
  123.  
  124. //First I will set up a 5 day work week calendar called FiveDay.
  125. //Calendar names can be up to 8 characters long and MUST start
  126. //with a letter. 
  127.  
  128. //Calendar FiveDay will have rest on Saturday and
  129. //Sunday but no holidays.
  130.  
  131. //Holidays for FiveDay
  132.  
  133. //Rest for FiveDay
  134. FiveDay sat
  135. FiveDay sun
  136.  
  137.  
  138. //Next I will set up a six day calendar that rests only on Sunday
  139. //and has no holidays.
  140.  
  141. //Holidays for SixDay
  142.  
  143. //Rest for SixDay
  144. SixDay sun
  145.  
  146.  
  147. //Finally I will setup a calendar that rests on Saturday and Sunday
  148. //and has standard US Holidays for 1993.
  149.  
  150. //Holidays for HolsFive
  151. HolsFive 18-jan-93
  152. HolsFive 25-feb-93
  153. HolsFive 31-may-93
  154. HolsFive 5-jul-93
  155. HolsFive 6-sep-93
  156. HolsFive 11-nov-93
  157. HolsFive 25-nov-93
  158. HolsFive 24-dec-93
  159. HolsFive 31-dec-93
  160.  
  161. //Rest for HolsFive
  162. HolsFive sat
  163. HolsFive sun
  164.  
  165.  
  166.  
  167. 4. Compiling the Calendar File
  168. ---------------------------------------------------------------------
  169.  
  170. Before DATEMATH can use the user defined calendars, the calendar text
  171. text file must be compiled. This is done with the program CalMaint.EXE.
  172. CalMaint first examines the calendar text file and produces a matrix
  173. display of the users calendars. Once the you is statisfied with the
  174. results CalMaint will compile the text file into a binary. The default
  175. name for the Calendar Text file is Caldata.TXT. The default name for
  176. the calendar binary file is Caldata.BIN. 
  177. The program CalMaint.EXE is not included in the demo version of 
  178. DATEMATH. However the user may test the software completely in there
  179. own programs with the Caldata.BIN file provided. As shown in the 
  180. previous section, this calendar file has three user defined work
  181. calendars in it. 
  182.  
  183. 1. FiveDay - Rest on Saturdays & Sundays, No Holidays
  184. 2. SixDay  - Rest on Sundays, No Holidays
  185. 3. HolsFive- Rest on Saturdays & Sundays plus Std US Holidays for 1993
  186.  
  187. If you choose to register DATEMATH you will recieve CalMaint.exe ( so
  188. you can compile your own calendars ) at no extra cost.
  189.  
  190.  
  191.  
  192. 5. DATEMATH's Library Functions
  193. ---------------------------------------------------------------------
  194.  
  195. The five functions included in the DATEMATH DLL are as follows:
  196.  
  197. Function Name        Ord  Rcv/Snd          Type        Parameter    Description/Sample
  198. ---------------------   ---  -------            -----           ---------       -------------------
  199. LoadCalendar        1    (R)        LPINT        nMemRef        memory tag
  200.                 (S)        LPSTR        szCalFile    'c:\caldata.bin'
  201. DCalDIF            2    (S)        LPINT        nMemRef        memory tag
  202.                 (S)        LPSTR        szCalendar    'ADMIN'
  203.                 (S)        LPSTR        szStartDate    '1993-01-01'
  204.                 (S)        LPSTR        szFinDate    '1993-01-31'
  205.                 (R)        LPINT        nDaysDif    result difference in days
  206. DCalADD            3    (S)        LPINT        nMemRef        memory tag
  207.                 (S)        LPSTR        szCalendar    'ADMIN'
  208.                 (S)        LPSTR        szDateIn    '1993-01-01'
  209.                 (R)        LPSTR        szDateOut    date result
  210.                 (S)        LPINT        nDaysAmt    days to add    
  211. DCalSUB            4    (S)        LPINT        nMemRef        memory tag
  212.                 (S)        LPSTR        szCalendar    'ADMIN'
  213.                 (S)        LPSTR        szDateIn    '1993-01-01'
  214.                 (R)        LPSTR        szDateOut    date result
  215.                 (S)        LPINT        nDaysAmt    days to substract
  216. DestroyCalendar        5    (R)        LPINT        nMemRef        releases calendar memory
  217.  
  218.  
  219. They are defined in Visual Basic AS:
  220.  
  221. Declare Function LoadCalendar Lib "DateMath.DLL" (nMemRef%, ByVal szCalFile$) As Integer
  222. Declare Function DCalDIF Lib "DateMath.DLL" (nMemRef%, ByVal szCalendar$, ByVal szStart$, ByVal szFinish$, nDaysDif%) As Integer
  223. Declare Function DCalADD Lib "DateMath.DLL" (nMemRef%, ByVal szCalendar$, ByVal szStart$, ByVal szFinish$, nDaysDif%)